Developer CD Series 1996 February: Tool Chest/Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso/Tool Chest/Testing & Debugging/Virtual User tools/SPEC S&L v.1.0.1/Libraries/FileTool.Lib

Text File | 1993-12-17 | 18.6 KB | 589 lines | [TEXT/MPS ]

#
# ****************************************************************************
#
#    File Name:    FileTool.Lib
#
#    Contains:    Derived from FileTool.vulib
#
#    Written by:    NAGA, Kevin Avoy et al
#
#    Copyright:    © 1993 by Apple Computer, Inc., all rights reserved.
#
# ****************************************************************************
#            C h a n g e        H i s t o r y (most recent first):
# ****************************************************************************
#
#        Vers      Date        Author        Description
#        ----    --------    ------    ---------------------------------------------
#     <1.0.2>     12/6/93    RTV        Synched original & SPEC S&L vers of this lib
#     <1.0.1>     5/21/93    KTA        Added ReadLine2(), ExistsOrCreate(), InitFileTool()
#     <1.0.0>     5/21/93    NAGA    Created
#
# ****************************************************************************
#

tool FileTool s:'FILE'
begin
    # Services specific to FileTool:

    # To create a file
    Service    "Create"( 'string', 'string', 'string' ) return 'integer';
    # first parameter is the Fullpath name for the file
    # second parameter is the 4 character signature (creator eg., 'MPS ')
    # third parameter is the 4 character file type (eg., 'TEXT')
    # return value is the file reference number for future calls

    # To create a folder
    Service    "CreateFolder"( 'string' ) return 'integer';
    # first parameter is the Fullpath name for the file
    # return value is the file reference number for future calls

    # To delete a file/folder
    Service    "Delete"( 'string', 'integer' );
    # first parameter is the Fullpath name for the file (can be '', if second
    # parameter is given non zero value)
    # second parameter if non-zero is the file reference previously
    # returned by the tool
    # once a file/folder is deleted its reference number is no longer valid

    # To erase the contents of the data fork of a file
    Service    "Erase"( 'string', 'integer' ) return 'integer';
    # first parameter is the Fullpath name for the file (can be '', if second
    # parameter is given non zero value)
    # second parameter if non-zero is the file reference previously
    # returned by the tool

    # To check if a file exists
    Service    "FileExists"( 'string' ) return 'integer';
    # first parameter is the Fullpath name for the file (can be '', if second
    # parameter is given non zero value)
    # the return value is 1 if file exists else 0

    # To check if a file exists
    Service    "CopyFile"( 'string', 'integer', 'string' ) return 'integer';
    # first parameter is the Fullpath name for the file (can be '', if second
    # parameter is given non zero value)
    # second parameter if non-zero is the file reference previously
    # returned by the tool
    # third parameter is the new file name (not a path name)
    # the return value is 1 if file copied else 0

    # To get back memory in the FileTool
    Service    "ForgetFile"( 'string', 'integer' ) return 'integer';
    # first parameter is the Fullpath name for the file (can be '', if second
    # parameter is given non zero value)
    # second parameter if non-zero is the file reference previously
    # returned by the tool
    # the return value is insignificant

    # To move a file/folder
    Service    "Move"( 'string', 'integer', 'string' ) return 'integer';
    # first parameter is the Fullpath name for the file (can be '', if second
    # parameter is given non zero value)
    # second parameter if non-zero is the file reference previously
    # returned by the tool
    # third parameter is the new file path name
    # return value is the file reference number for future calls

    # To read from a file a specified number of characters
    Service    "Read"( 'string', 'integer', 'integer', 'integer' ) return 'string';
    # first parameter is the Fullpath name for the file (can be '', if second
    # parameter is given non zero value)
    # second parameter if non-zero is the file reference previously
    # returned by the tool
    # third parameter is the number of characters to be read
    # fourth parameter is the number of characters from start of file after which to start reading
    # return value is the string read from the file

    # To read from a file until a specified character is seen
    Service    "ReadUntil"( 'string', 'integer', 'string', 'integer' ) return 'string';
    # first parameter is the Fullpath name for the file (can be '', if second
    # parameter is given non zero value)
    # second parameter if non-zero is the file reference previously
    # returned by the tool
    # third parameter is the single character strinng that indicates the
    # character until which the contents of a file has to be read
    # fourth parameter is the number of characters from start of file after which to start reading
    # return value is the string read from the file

    # To rename a file/folder
    Service    "Rename"( 'string', 'integer', 'string' ) return 'integer';
    # first parameter is the Fullpath name for the file (can be '', if second
    # parameter is given non zero value)
    # second parameter if non-zero is the file reference previously
    # returned by the tool
    # third parameter is the new file name (not a path name)
    # return value is the file reference number for future calls

    # To get back the list of mounted volume names
    Service    "VolumeList"() return 'list';

    # To write to the data fork of a file
    Service    "Write"( 'string', 'integer', 'string' ) return 'integer';
    # first parameter is the Fullpath name for the file (can be '', if second
    # parameter is given non zero value)
    # second parameter if non-zero is the file reference previously
    # returned by the tool
    # third parameter is the text to be appended to (written at the end
    # of) the file specified by the first two parameters
    # return value is the file reference number for future calls

    # To append the second file to the first, both must be text files
    Service    "AppendFile"( 'string', 'string' ) return 'symbol';

    # To locate the special folders defined by the system
    # first parameter is the four character code for the folder, the FolderType
    # the full path name to the folder is returned
    Service    "FindFolder"( 'string' ) return 'string';

    # Read the short & long version string from the specified file
    Service    "ReadVersion"( 'string', 'integer' ) return 'list';

    # Test if a resource exists within a specified file, return true if so
    Service    "ResourceExists"( 'string', 'string', 'integer' ) return 'symbol';

    # Services common to all Virtual User external tools:
    Service "Initialize"( 'undefined' );        # pass TRUE for target, FALSE for host
    Service "Cancel"( 'string' );
    Service "GetToolServices"() return 'list';
    Service "GetToolVersion"() return 'list';
    Service "ServiceSupported"( 'string' ) return 'undefined';
    Service "Quit"();

end;

task CreateFile( pFilePathName, pSignature := 'MPS ', pType := 'TEXT' )
begin
    return FileTool( "Create", pFilePathName, pSignature, pType );
end;

task CreateFolder( pFolderPathName )
begin
    return FileTool( "CreateFolder", pFolderPathName );
end;

task DeleteFile( pFileReference )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber as parameters
    return FileTool( "Delete", tFilePathStr, tFileReferenceNumber );

end;

# This task will empty the contents of the specified file (dataFork only)
# the file will not be deleted
task EraseFile( pFileReference )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber as parameters
    return FileTool( "Erase", tFilePathStr, tFileReferenceNumber );

end;

task FileExists( pFilePathName )
begin
    if( typeOf( pFilePathName ) <> 'string' )
    begin
        return -50;#gParamError = -50, same as what the tool returns
    end;

    # Now call the tool with pFilePathName as parameter
    return FileTool( "FileExists", pFilePathName );

end;

task FileCopy( pFileReference, pDestPathName )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pDestPathName as parameters
    return FileTool( "CopyFile", tFilePathStr, tFileReferenceNumber, pDestPathName );

end;

# This task will free up memory in the FileTool
# the file will not be touched or affected in any way
task ForgetFile( pFileReference )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber as parameters
    return FileTool( "ForgetFile", tFilePathStr, tFileReferenceNumber );

end;

task MoveFile( pFileReference, pNewPathName )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pNewPathName as parameters
    return FileTool( "Move", tFilePathStr, tFileReferenceNumber, pNewPathName );

end;

task RenameFile( pFileReference, pNewName )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pNewName as parameters
    return FileTool( "Rename", tFilePathStr, tFileReferenceNumber, pNewName );

end;

task VolumeList()
begin

    # Now call the tool
    return FileTool( "VolumeList" );

end;

# a utility task used by WriteToFile
task ToText( pData )
begin
    if( typeOf( pData ) = 'string' ) return pData;
    if( typeOf( pData ) = 'integer' ) return NumToStr( pData );
    return undefined; # else
end;

# This task will append pData to end of the specified file
# pData can a string or a list of strings and numbers
task WriteToFile( pFileReference, pData )
begin
    tText := '';
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    if( typeOf( pData ) = 'list' )
    begin
        for i := 1 to card pData
        begin
            tNext := ToText( pData[i] );
            if( tNext )
                tText := tText + tNext;
            else
                return -50;
        end;
    end;
    else if( typeOf( pData ) = 'string' )
    begin
        tText := pData;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and tText as parameters
    return FileTool( "Write", tFilePathStr, tFileReferenceNumber, tText );

end;


task Read( pFileReference, pNumOfCharacters, pFromPosition := 0 )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pNumOfCharacters as parameters
    return FileTool( "Read", tFilePathStr, tFileReferenceNumber, pNumOfCharacters, pFromPosition );

end;

task ReadUntil( pFileReference, pUntilCharacter, pFromPosition := 0 )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pUntilCharacter as parameters
    return FileTool( "ReadUntil", tFilePathStr, tFileReferenceNumber, pUntilCharacter, pFromPosition );

end;

task ReadLine( pFileReference, pFromPosition := 0 )
begin
    return ReadUntil( pFileReference, "∂n", pFromPosition );
end;




task AppendFile( pTargetFile, pSourceFile )
begin
    if not ( typeOf( pTargetFile ) = 'string' )
    begin
        return { -50 };#gParamError = -50, same as what the tool returns
    end;

    if not ( typeOf( pSourceFile ) = 'string' )
    begin
        return { -50 };#gParamError = -50, same as what the tool returns
    end;

    # Now call the tool with tTargetFile, tSourceFile
    x := FileTool( "AppendFile", pTargetFile, pSourceFile );
    return x;
end;

task FindFolder( FolderType )
begin
    if not ( typeOf( FolderType ) = 'string' )
    begin
        return { errAEWrongParameters, undef, "Bad FolderType parameter" };
    end;

    if ( card( FolderType ) > 4 ) or ( card( FolderType ) <= 0 )
    begin
        return { errAEWrongParameters, undef, "Bad FolderType parameter" };
    end;

    x := FileTool( "FindFolder", FolderType );
    return x;
end;

#########################################################################
#        InitFileTool(pOnTheTarget := true)
#========================================================================
# Author:        Kevin Avoy (x4-5604)
# Description:    Initializes the FileTool
# Parameters:    pOnTheTarget - True if you want to launch the FileTool on
#                                the target machine. False if on the Host.
# Returns:        Nothing
# Examples:        InitFileTool();
# Assumptions:    None
#========================================================================
# History:
#
#########################################################################
TASK InitFileTool(pOnTheTarget := true)
begin
    returnVal := 0;
    FileToolInit :=  FileTool("Initialize", pOnTheTarget );         # Launch FileTool on Host
    if FileToolInit[1] <> 0                                    # If error during initialization,
    begin
        println "FileTool could not be initialized";        # print error
        println "Error ", FileToolInit[1], ". ",  FileToolInit[3] ;
    end;
    else
    begin
        println "FileTool Initialized properly";
        returnVal := 1;
    end;

    return(returnVal);
end;


#########################################################################
#        ReadLine2( pFileReference, pFromPosition )
#========================================================================
# Author:        Kevin Avoy (x4-5604)
# Description:    Similar to ReadLine Above except this routine does the error
#                checking and will return 0 if an error occur otherwise it will
#                what the line that was read (2nd element of what theFileTool returned)
# Parameters:    pFileReference - File to read from.
#                pFromPosition - position to begin reading from.
# Returns:        0 - Some Error
#                String - line read
# Examples:        ReadLine2('hd:myFile', 0);
# Assumptions:    None
#========================================================================
# History:
#
#########################################################################
task ReadLine2( pFileReference, pFromPosition := 0 )
begin
    theLine := ReadUntil( pFileReference, "∂n", pFromPosition );
    if(theLine[1] <> 0)
    begin
        println "Problem reading the file";        # print error
        println "Error ", theLine[1], ". ",  theLine[3] ;
        returnVal := 0;
    end;
    else
        returnVal := theLine[2];
    return (returnVal);
end;


#########################################################################
#                        ExistsOrCreate()
#========================================================================
# Author:        Kevin Avoy
# Description:    Checks to see if the <pFileName> exists - creates one if it does not.
# Parameters:    pFileName - full path of file
# Returns:        0 - Fail (doesn't exist, couldn't create)
#                1 - File Existed
#                2 - Created File
# Examples:        ExistsOrCreate();
# Assumptions:    None
#========================================================================
# History:
#
#########################################################################
task ExistsOrCreate(pFileName)
begin
    returnVal := 0;
    ###    Create the file only if it doesn't exist
    x := FileExists( pFileName );
    if not (TypeOf( x ) = 'list' and x[1] = 0)
    begin
        ###    Create the File
        CreatedFile := CreateFile( pFileName );
        If(CreatedFile[1] <> 0)
        begin
            Println "!@#$% An error occured while creating the file";
            Println "Error", CreatedFile[1], CreatedFile[3];
        end;
        else    # File was created
            returnVal := 2;
    end;
    else        # File must Exist
        returnVal := 1;

    return(returnVal);
end;


#########################################################################
#                        ReadVersion()
#========================================================================
# Author:        Rick Violet
# Description:    Returns the short & long version strings from the 'vers' resource
# Parameters:    FilePathName     - full path of file
#                pVersID         - 'vers' resource's id
# Returns:        undefined         - if resource not found
#                { shortString, longString } - if successful
# Examples:        ReadVersion();
# Assumptions:    None
#========================================================================
# History:
#
#########################################################################
task ReadVersion( FilePathName, pVersID := 1 )
begin
    x := FileTool( "ReadVersion", FilePathName, pVersID );
    SErr := ScriptError();
    return { x[1], x[2], x[3], SErr };
end;

#########################################################################
#                        ResourceExists()
#========================================================================
# Author:        Rick Violet
# Description:    Checks to see if the resource exists.
# Parameters:    FilePathName - full path of file
#                pResType      - resource's type
#                pResType      - resource's ID
# Returns:        0 - Fail (doesn't exist )
#                1 - resource Exists
# Examples:        ResourceExists();
# Assumptions:    None
#========================================================================
# History:
#
#########################################################################
task ResourceExists( FilePathName, pResType, pResID )
begin
    x := FileTool( "ResourceExists", FilePathName, pResType, pResID );
    SErr := ScriptError();
    return { x[1], x[2], x[3], SErr };
end;